Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / lib / tcl / mxedit.tutorial < prev next >

Wrap

Text File | 1992-07-15 | 28.5 KB | 528 lines

-------------------------------- Mx Tutorial #1: Basic Editing -------------------------------- by John Ousterhout (updated for mxedit by Brent Welch) This document is an introduction to Mx, which is a mouse-based editor for use with the X window system. The best way to read this tutorial is on-line in an Mx window, so that you can try out the commands as they are introduced. To access this tutorial on-line, invoke the shell command "mxedit" with no arguments. Simple Scrolling: ---------- The first thing for you to learn is how to move around within a file, so that you can at least read the tutorial. This is called "scrolling". The easiest way to scroll is by "dragging" the document: hold down the shift key with your left hand, place the pointer over the center of this window, press the left mouse button, and move the mouse up and down while holding the button down. As you move the mouse, the document will move up and down in the window. In the shorthand notation I'll use in the tutorial, what you just did is called "shift-left-dragging". If you'd like to move the document more quickly, for example to browse through it quickly, try shift-right-dragging (use the right mouse button instead of the left). In this case, the document will move a lot in response to very small mouse motions. The vertical strip on the left side of the Mx window is called the "scrollbar". A small box is displayed inside the scrollbar. I call this the "elevator". Its height and location indicate which portion of the file is visible in the window. For example, if the top of the elevator is at the top of the scrollbar and the bottom of the elevator is halfway down the scrollbar, it means that the first half of the file is visible in the window. Try dragging up and down and see how the elevator moves. You can also scroll by pressing mouse buttons with the pointer over the scrollbar. Clicking on the arrows at either end of the scrollbar cause the display to scroll up or down by one line. You can click on the elevator and drag it up or down and you'll get an effect similar to the shift-dragging described above. If you click in the gaps between the elevator and the arrows then you scroll up or down one page. In this case one line of context is kept so that, for example, clicking on the gap above the scrollbar the line at the top of the window will move to the bottom. If you have a reasonably fast display, you'll probably find that it's more convenient to scroll by dragging than by clicking in the scrollbar. Basics: ------- Mx is a simple editor that allows you to examine and modify text files. It provides basic editing functions such as insertion, deletion, copying, searching, and substitution. It also supports multiple windows. You can display several different files at the same time in different windows and copy information back and forth between them, and you can look at several different regions of the same file at the same time using a different window for each region. Each Mx window contains several subwindows. The top-most subwindow is normally a title bar displayed by the window manager. The title bar displays the name of the file you're editing. If you've modified the file, then an exclamation point will appear after the file's name (or the word "Modified" will appear at the right side of the title bar). Just underneath the title bar is the "menu bar", which contains the names of several pull-down menus. At the bottom is a message window, which currently gives the name and size of this file. Information and error messages will appear in the message window at various times during editing. At the left side of the window is the scrollbar, which you're already familiar with. The rest of the window displays a few lines of the file you're editing. A few other subwindows will appear later on, while you're editing. For example, one of them will be used to enter strings for searching and replacement. There are three ways that you can invoke operations in Mx: by positioning the pointer over the text of the file and clicking or dragging with the mouse, by typing keys on the keyboard, or by selecting menu entries with the mouse. For a simple example of each of these, first move the pointer over the leftmost "X" in the line below and left-click. A little upside-down "V", called the "caret", will appear just to the left of the X. XXXX - play here Second, type some characters on the keyboard. Each keystroke invokes an Mx command to insert that character into the file just before the caret. As you'll see later, various special keys, such as the control keys, can be used to invoke other Mx commands such as copying and deleting text. Finally, for an example of a menu selection, move the pointer up to the menu bar (it's the horizontal strip at the top of the window just underneath the striped title bar), and position it over the word "Edit". The word will highlight. Press the left mouse button and hold it down. This causes a menu to appear underneath the pointer. With the button held down, drag the pointer down through the menu until the word "Undo" is highlighted, then release the mouse button. This invokes the undo command, which will remove all the text you just typed in. Each word in the menu bar corresponds to a different menu. To scan through the menus, press the left mouse button with the pointer over "File", and hold the button down. Then drag the pointer to the right so that it passes in turn over each of the other words in the menu bar. When an error occurs while Mx is executing a command, Mx will tell you in one of two ways. For short messages, Mx will place the message in the message subwindow. If an error message is long, or if Mx needs for you to make a decision, it will pop up a special window called a "notifier". The notifier contains a message plus one or more options, which appear at the top of the notifier. When you see a notifier, you must click on one of the options in order to tell Mx what to do. For example, insert some characters in this file then invoke the "Quit" entry in the "File" menu. A notifier will warn you that you're about to lose the changes you just made to this file. Click a mouse button on the "Skip command" option. The Caret and Insertion: ------------------------ The simplest operation in Mx is insertion. If you type normal characters on the keyboard, they will be inserted in the file at the position of the caret. You can position the caret anywhere in the file by left-clicking or left-dragging. If you make mistakes while you're typing, you can type control-h, BACKSPACE, or DELETE to delete the character just before the caret. Control-w will delete the entire word that precedes the caret. Try inserting text at various positions within this file. The Selection: -------------- The selection is a special range of text used in operations like copying and deletion. To select a range of characters, position the caret at one end of the range, then move the pointer to the other end of the range and right-click. All of the characters between the caret and the pointer will become highlighted. These characters constitute the selection. Try changing the selection by moving the pointer somewhere else and right-clicking. You can drag the end of the selection by moving the mouse with the right button held down, just as you can drag the caret by moving with the left button down. Try selecting various ranges of text in this tutorial. There can only be one selection at a time: when you make one selection, the previous one disappears. There are additional selection modes called "word selection" and "line selection". To invoke word selection, point to a character in the middle of a word and left-click twice in a row (quickly) without moving the mouse. This is called "double-clicking", and will cause the entire word to be selected. When you right-click now, Mx will ensure that only whole-words are selected. If you triple-click the left button, then Mx will force the selection to consist of entire lines of the file. Try making word and line selections. A word is any collection of adjacent letters and digits. Each punctuation character is considered to be a word by itself, except that the bracket characters "()[]{}<>" are treated specially. When you use word selection on a bracket character, Mx finds the matching bracket and selects the entire range, including the open and close brackets. Brackets may be nested. Double-click in the code fragment below and hold the left button down during the second click. Then drag the pointer around to see what happens when it passes over the various brackets: if (template != NULL) { x = (foo[index+2, y] + (x/y)*42)/(y+1); y = 0; } If you only want to select a single character, there is a faster way than first left-clicking to position the caret at one side of the character and then right-clicking to select the character. Instead, "roll" the mouse buttons: press left then immediately press right before you've released left. This will select the character under the pointer and also place the caret at the left side of the character. If you hold one or both of the mouse buttons down after you've rolled, you can drag both the caret and the selection. There are times when it's convenient to make a selection without moving the caret (e.g., you've already got the caret where you want it and you'd like to select some text to copy to the caret position). To do this, hold the control key down while you select. Control-left-click will select the character under the pointer without moving the caret, and control-right-click will select the range of characters between the pointer position and the character that you selected with control-left-click. Copying and Deleting: --------------------- The selection is used for many purposes in Mx, the most common of which are deleting and copying. You can delete a range of text by selecting the text and then invoking the "Delete SEL" entry in the "Edit" menu. Throughout the Mx menus, the term "SEL" refers to the selection. Note that you can select the newline character at the end of a line (when it's selected, all of the white space at the end of the line is highlighted); if you delete the newline character, the following line will be joined to the current line. The "Paste" entry in the "Edit" menu will insert a copy of the selection at the position of the caret, even if the selection currently belongs to some other X tool. The "Move SEL" entry in the "Edit" menu will move the selection to the caret position, but only if the selection is in the current window. Some people find it most convenient to first select the text to be copied or moved and then position the caret at the destination; others find it more convenient to position the caret first, then hold the control key down while selecting the text. Try using copy and delete to exchange the words "red" and "house" in the sentence below. Then use move to put "red" back where it was originally. Thank goodness they're repainting their house red. Cut and Paste with the Function Keys: ------------------------------------- Some keyboards have function keys labeled "Cut", "Paste", and so on. These keys are bound to the corresponding operations, at least they are for the Sun keyboards. There is, however, one subtle difference in the way Mx manages the selection and the way it is done by other tools. There is no explicit "Copy" operation in Mx. Instead, when you make a selection using the mouse it is automatically registered as the primary X selection. The good part of this is that it is fast and easy to select something. The down-side is that it is also easy to accidentally make a new selection and make Mx forget what was selected previously. Another difference is that many applications use "Cut" to put things into the X "cut buffer", with "Paste" being used to insert the contents of the cut buffer. For now, anyway, Mx just implements a per-window cut buffer so that pressing "Cut" and then "Paste" in the same window will work as you expect. However, if there is a primary selection registered (i.e., if you have selected text in Mx), then "Paste" will insert that instead of the contents of the per-window cut buffer. Also, "Cut" then "Paste" won't work between windows. Instead, to transfer information between windows, just select it in the Mx window, and then use "Paste" to copy it into another X tool. Finally, Mx has a "Move SEL" menu entry that will move the selection to where the current insert point is, which is equivalent to Cut-then-Paste. Saving Files and Leaving the Editor: ------------------------------------ When you're ready to leave the editor, select the "Quit" entry in the "File" menu. This will destroy the X window. It will also end the execution of Mx, if there are no other Mx windows open. When you make changes to a file in Mx, those changes are not automatically reflected in the original copy of the file on disk. To change the disk version of the file, you must "save" the file. The "Save" entry in the "File" menu will write the file back to disk. Or, if you've modified the file and then try to quit without saving the file, Mx will warn you with a notifier and give you a chance to save the file or skip the quit command. If you'd like to save the edits in a different file than the one you started out with, select the name of the file you'd like to save into and then invoke the "Save in file SEL" entry in the "File" menu. The only problem here is how to get the file name someplace where you can select it. If it already appears on the screen somewhere, just select it. As a last resort, open the command subwindow by invoking the "Command" in the "Window" menu. The cursor (a thin vertical line) should appear in the small subwindow that just appeared at the bottom of the window. Then type the file name there and select it for use in saving the file, or go ahead and type "save filename" to the Command: prompt. After saving the file, you can make the command subwindow go away by getting the caret into the command subwindow (if it isn't there already, invoke the "Open command subwindow" menu entry again, or left-click in the command subwindow) and typing control-q. In general, typing control-q in an Mx window or subwindow is a request to make the (sub)window go away. Bindings: ---------- The menus are convenient for learning because they're easy to browse through to find commands. However, if you use the menus a lot you won't be able to edit very quickly. Fortunately, many of the Mx commands can be invoked by typing keys as well as by selecting menu entries. The keystrokes are called "bindings": a particular key or sequence of keys is "bound" to an Mx command. If there is a keystroke sequence equivalent to a menu entry, the binding appears at the right side of the menu entry. For example, the "Paste" entry in the "Edit" menu shows the binding <Control-v>. The "Delete" entry in the same menu has the binding <Control-d>. These two bindings and the control-q binding mentioned above are the most important ones; I suggest that you learn them immediately and use them instead of the menu entries. You can gradually learn other bindings as you become more familiar with the system. To get information about all of the default bindings, invoke the "Show key bindings" entry in the "Help" menu. The binding <Mod1-x> in a menu means "meta-x", which means different things on different keyboards. On Sun-4 keyboards, the meta key is labeled "Alt". Use the meta key like the control key, hold it down while pressing the other key given in the binding sequence. In contrast, the Escape key is used by first pressing the Escape key and then pressing another key. Bindings for escape sequences look like <Escape><x>. You can change the bindings to eliminate old ones and define new ones if you wish. You can also modify the menus, or even change the meanings of normal keystrokes (for example, you could arrange things so that typing the space character caused the selection to be deleted, if that turned out to be desirable). For more information, see the section below on Customizing the Editor. Undoing and Crash Recovery: --------------------------- While you edit, Mx keeps a log of every modification that you make to the file. The log is used for two purposes: undoing and recovery. If you ever make a change and then wish you hadn't, you can invoke the "Undo" entry in the "Edit" menu or type the <Control-u> binding. This will cause the last modification you made to the file to be undone. If you undo several times in a row without any intervening file modifications, each invocation will undo the next older action, all the way back to the beginning of the edit session. Make a series of changes to this file, then undo them. Normally, each user-invoked action, such as a keystroke or button click or menu selection, constitutes one event as far as undoing is concerned. Thus if you copy a huge selection, the whole copy will be undone at once. The only exception to this rule is that if you type in a bunch of text on the same line, then all of the text will be undone together (i.e. you don't have to invoke undo once for each character; use backspace or control-W if you only want to erase a few characters). If you type in many lines of text in a row, then the type-in will be undone one line at a time. The undo actions are recorded in the log, so they can be undone also. However, if you undo something and then wish you hadn't, you can't just undo again: that will undo the next next older action, rather than undoing the undo. Instead, hit the space bar, which inserts a space character in the file. This (or any other modification to the file) resets the undo mechanism so that the next undo refers to the most recent modification to the file; now invoke undo twice: the first will undo the space insertion and the second will undo the unwanted undo. The second purpose of the log is to allow recovery if Mx crashes during an edit session or if your machine goes down unexpectedly. If a crash occurs, the log file will be left on disk. The log file has a name beginning with "Mx" and is usually stored in the directory containing the file being edited. If that directory isn't writable, then Mx stores the log file in your home directory. To recover all the changes you made during a crashed edit session, just re-run Mx on the same file. Mx will locate the log file [and pop up a notifier giving you the choice of recovering or deleting the old log file. If you select recovery,] Mx will scan through the log file and update the file to reflect all of the changes made in the crashed edit session. With the recovery mechanism, you should never lose any modifications except for those on the line where you were working when the crash occurred. You can try out the recovery features by starting up Mx and then killing it from the shell. Searching and Substitution: --------------------------- Mx provides mechanisms that allow you to search through a file for a particular sequence of characters, or to replace a given sequence of characters with another sequence provided by you. To see how this works, invoke the "Forward" entry in the "Search" menu. The first time you invoke this operation, Mx will open a new subwindow just under the menu bar, called the "search subwindow". It contains two entry areas, where you can type in a search string and a replacement string. To enter a search string, get the caret into the search entry (if it isn't already there) by moving the pointer over the entry and left-clicking. Now you can type in a search string. The editing characters <Control-h> and <Control-w> work in the search subwindow, and you can also use the selection and <Control-d> to edit the search and replacement strings. You can use <Control-v> to copy information from almost anywhere on the screen to the search and replacement strings. Enter the characters "the" as the search string. There are four different ways you can invoke searching now. The simplest is to press RETURN in the Search window, or you can re-invoke the "Forward" entry in the "Search" menu. Mx will search for the next occurrence of the string "the", starting at the caret location, and will select that occurrence. You can also search using the <Control-f> binding in the main window, [or by middle-clicking on the search string]. These four approaches all produce the same result. The "Search" menu provides a "Backward" entry to scan in the opposite direction. If one end of the file is reached during a search, Mx skips to the opposite end of the file and continues. If you don't want to type the search string into the search subwindow, you can also select the string you'd like to search for and use the "Forward for SEL" and "Backward for SEL" menu entries. To make substitutions, enter a replacement string into the search subwindow and invoke the "Replace" command in the "Search" menu. This will replace the selection with the replacement string. You can also invoke replacement by typing RETURN in the replacement string, [by middle-clicking on the replacement string], or by typing the <Control-r> binding in the main window. You can move the focus from the Search entry to the Replace entry with the binding <Control-r>. You can move the focus from the Replace entry to the search entry with the <Control-f> binding. By default, search and replacement strings are regular expressions in the style of the vi text editor. If you'd prefer for searching and replacement to be done by exact matches only, without regular expressions, set the "noRegExps" variable to 1. If you'd like to replace all the instances of one string by another string, you have two choices. One possibility is repeatedly to type <Control-f> and <Control-r> to step through the instances one at a time. Or, you can select a range of text in which you'd like to make the substitution and invoke the "Replace in SEL" entry in the "Search" menu. This will replace all instances of the search string in a single operation. Try using these commands to replace "the" with "my" in several areas of this document. The "Replace in SEL" command is bound to <Mod1-r>. The "Replace Everywhere" entry in the "Search" menu will make the substitution throughout the file. Two other bindings are useful when searching and replacing: <Escape><f> will clear the search string entry and move the caret there, so you can type in a new search string; and <Escape><r> will clear the replacement string entry and move the caret there When you no longer need the search subwindow, you can get rid of it by getting the caret into it (left-click on the window if necessary) and typing "C-q". Using Multiple Windows: ----------------------- Mx allows you to open several windows on the same or different files and copy information back and forth between them. Invoke the "Open" entry in the "File" menu. The new window will display the same file as the old window, and you can modify the file from either window. Try making changes in both windows: you'll see the selection and the changes in each of the windows. You can also open a new window on a different file by selecting the file's name and invoking the "Open file SEL" entry in the "File" menu. Once this is done, you can use the selection to copy information back and forth between the windows. The "File" menu also includes additional entries for switching the current window from one file to another ("Switch to file SEL"), opening a new window (or switching the current window) to display the definition of a symbol using the tags facility, and adjusting the view in a window to display a particular line number (e.g. for compiler error messages). Indentation: ------------ Mx automatically manages line indentation. Whenever you type RETURN to start a new line, Mx will indent the new line to match the indentation of the previous line. Whenever you move the caret away from a line Mx will clean up the line's indentation: if there is any white space at the beginning of the line, Mx replaces as much of it as possible with tabs (one tab for each eight spaces). In the lines below, position the caret at the end of the various lines and type RETURN to see how auto-indentation works: This line is indented. This line is indented even more. The "Edit" menu provides several commands to modify the indentation of lines. First, the variable "indent" is used to keep the current value of indentation. This defaults to 4, although you can change this in your .mxedit file. "Indent SEL" will shift all the lines in the selection right by $indent spaces, and "Outdent SEL" will shift the lines left by $indent spaces. "Indent line" and "Outdent line" do the same thing for the line containing the caret. History and Repeating Commands: ------------------------------- Mx automatically records commands you've invoked so that they can be replayed later. For full details, read about the "history" command in the manual page. The simplest mechanism is "Do again", which is available in the "Edit" menu or with the <Control-a> binding. This will repeat all the commands you invoked between the last two button presses, searches, or undos. For an example of how this works, select "Test" below, then delete it and type "Foo" in its place. Then select "Test2", and type <Control-a>; you can continue with "Test3" and "Test4" also. Test Test2 Test3 Test4 Command subwindow: ------------------ The command subwindow is displayed at the bottom of the window along with the "Command:" prompt. The things you type into this window are interpreted as TCL commands, so you can play around a bit. This is useful to test out customizations as described below. I also find it easiest to open new windows and switch among files using the command window. You can display the command window if it isn't already visible by typing <Control-c> in the main editing window, or by selecting the "Open command window" entry in the Window menu. You can hide the command window by typing <Control-q> in the command window or by selecting the "Hide command window" entry in the Window menu. Customizing the Editor: ----------------------- You probably hate the built-in keystroke bindings already, plus you can imagine more menus that you'd like to add to the editor. These are all defined by TCL commands, so you can change these by putting TCL commands into a file called ".mxedit". The editor looks in your home directory and in the current directory for these files each time it creates a new top-level window. You can define new keystroke bindings, menus, and TCL procs. If you want to get serious you should look at the mxedit.* scripts in the TCL library directory to see how the base editor is implemented. You'll also want to understand how mxedit uses marks, which is explained in README.mxedit The mxBind command binds a key sequence to a command. It is a thin layer on top of the TK bind command, so you should read the TK bind man page for details. man -M /project/tcl/man bind The command can be any TCL proc, including those defined in mxedit.utils and those you define yourself. Try grepping through mxedit.utils for '^#.* --' to get a list of the procs defined there. Look also at mxedit.bindings to see how the default keystroke bindings are setup. Here is a silly example that binds <Control-x> to look for the string "foo": mxBind <Control-x> { search forw "foo" } You'll note that the menus list keyboard accelerators in them. It is possible to change keyboard bindings and update the menus at the same time by using the "mxMenuBind". In this case you specify a binding for a particular menu entry, and the procedure takes care of updating the menu to display the right accelerator: mxMenuBind <Control-f> Search "Forward" If you want to add a new menu use mxMenu to initialize it: mxMenu Test and then add things to it with mxMenuAdd mxMenuAdd Test "Do Something" { global a ; set a 5 } mxMenuAdd Test "See Something" { global a ; set a } and perhaps add a keyboard accelerator with mxMenuBind mxMenuBind Test "Do Something" <Control-x> Occasionally you'd like to change a menu's appearance as the result of running a command. Use mxMenuEntryConfigure: mxMenuEntryConfigure Test "Do Something" -label "Do Something Else" \ -command { global a ; set a -5 } All the mxMenu* commands are thin layers on top of the TK menu commands so you can consult the TK menu man page for details if you run into problems. The main difference is that the mxMenu* routines keep track of menus by their button label (e.g., "File") instead of an internal TK widget name (e.g., ".buttons.FileMenu"). Also, all keystroke sequences are bound to the main edit window. You'll have to come up with a new procedure based on mxMenuBind if you want to change that property.